Repository navigation
Move repeated inline page scripts, styles, and icons into shared assets - #2216
David Pine (IEvangelist) merged 5 commits into
Conversation
- Load the AppHost preference and WCP consent bootstraps as blocking, hashed /_astro/ scripts instead of inlining them in every page. - Bundle the Footer and OsAwareTabs scripts; OsAwareTabs now renders a marker read by a shared module. - Emit all JavaScript as files (no inline module scripts) and set build.inlineStylesheets to 'never'. - Render the sidebar caret and page-action external icon via CSS masks (Starlight / starlight-page-actions patches). Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Redirect every import of Starlight's Icon component to a wrapper that references common icons (site chrome, sidebar topics, socials, pickers, asides) from a hashed /_astro/ sprite via <use>, falling back to inline markup for any other icon. The sprite is generated from Starlight's icon set (bun run icon-sprite) and a unit test keeps it in sync. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
Astro's scoped class on the component tag replaced the class passed through the props spread, so icons like the live menu's external-link lost their styling hook. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Combined validation: real
|
| Before | After all four PRs | |
|---|---|---|
Ev2ServiceArtifactsRoot/Images/aspiredev.tar.gz |
~4 GB | 1.76 GB |
| Built HTML pages | 38,344 | 29,134 |
Site output (dist) |
9.8 GB | 3.73 GB |
wwwroot in image |
n/a | 3.73 GB originals + 0.68 GB .br |
The container starts in 11 s, /healthz returns 200, and idle memory is about 2 GB, likely from the 134 MB staticwebassets.endpoints.json.
Testing against the container
- Layout check: 35 representative layouts (docs, splash, hub, 404,
/de/fallback,/ja/translated, C#/TS/Go API landing, package, type and member pages) on desktop and mobile. Every page returned the expected status, with no failed requests and no page errors. - Full Playwright suite,
CI=1 bunx playwright test, all 3 projects, reusing the container on :4322: 1,632 passed, 5 failed, 2 flaky, 107 skipped. Failures are triaged below. - Manual testing of the running container found no issues.
This PR: docs pages drop about 85 KB each (install-cliwent from 260 KB to 175 KB, with 0 inline styles and about 6 KB of inline script). Two issues found in the combined run:
- Inline-fallback icons lost the caller's
class(Astro's scoped class replaces the spread class), so the live menu's external-link icons broke (live-status.spec.ts:703). Fix: passclass={Astro.props.class}explicitly (coordinator commit 8ba6fcce, being applied here). api-search-contract.spec.ts:248deadlocks: the test holds back every script, and the pre-paint bootstraps are now render-blocking<script src>. Being resolved in this PR.
Only the AppHost-preference bootstrap still blocks rendering as an external script. The WCP bootstrap only needs the parsed DOM, so it now loads with defer; its one pre-paint step (hiding cookie controls when a previous visit found consent isn't required) is a tiny inline snippet. The API search contract test now holds back only module scripts, as intended, instead of the classic pre-paint bootstrap that blocks parsing. Also cover the inline-fallback icon class regression in a unit test. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🔵 Needs a closer look
The page-wide Icon and asset/script changes lack confirmed standalone production CI and built-site validation, while the supplied browser results mainly cover dev mode or a combined-series image.
No open issues 🎉
What changed in this PR
This PR reduces repeated HTML in the aspire.dev static site by moving shared scripts, styles, and icons into cacheable assets, supporting the effort to shrink the frontend container image.
Changes:
- Externalizes preference and consent bootstraps and bundles footer and OS-aware tab behavior.
- Adds a shared icon sprite and replaces repeated sidebar and page-action SVGs with CSS masks.
- Updates build settings, generation tooling, and tests for shared-asset delivery.
| File | Description |
|---|---|
src/frontend/tests/unit/navigation-preferences.vitest.test.ts |
Checks external, blocking preference initialization. |
src/frontend/tests/unit/icon-sprite.vitest.test.ts |
Covers sprite consistency, references, and inline fallback classes. |
src/frontend/tests/unit/custom-components.vitest.test.ts |
Updates sprite and tab-marker assertions. |
src/frontend/tests/e2e/api-search-contract.spec.ts |
Allows pre-paint scripts through the controller gate. |
src/frontend/src/utils/icon-sprite.ts |
Defines shared icons and sprite generation helpers. |
src/frontend/src/scripts/wcp-consent.inline.js |
Extracts the consent bootstrap into an external asset. |
src/frontend/src/scripts/os-aware-tabs.ts |
Centralizes OS-based shell-tab defaults. |
src/frontend/src/scripts/apphost-preferences.inline.js |
Restores preferences and seeds the terminal default before paint. |
src/frontend/src/components/starlight/Icon.astro |
Uses sprite references with an inline fallback. |
src/frontend/src/components/starlight/Head.astro |
Loads external bootstraps while retaining minimal pre-paint consent logic. |
src/frontend/src/components/starlight/Footer.astro |
Bundles footer behavior and removes ineffective browser translation code. |
src/frontend/src/components/OsAwareTabs.astro |
Supplies sync-key markers to the shared initializer. |
src/frontend/src/assets/icons/starlight-icons.sprite.svg |
Adds the generated shared icon sprite. |
src/frontend/scripts/generate-icon-sprite.ts |
Generates the sprite from installed Starlight icons. |
src/frontend/patches/starlight-page-actions@0.7.0.patch |
Replaces external-link SVGs with CSS masks. |
src/frontend/patches/README.md |
Documents the expanded patch purposes. |
src/frontend/patches/@astrojs__starlight@0.41.3.patch |
Replaces sidebar caret SVGs with CSS masks. |
src/frontend/package.json |
Adds the sprite-generation command. |
src/frontend/eslint.config.mjs |
Configures linting for classic browser scripts. |
src/frontend/config/starlight-icon-sprite.mjs |
Redirects Starlight icon imports to the wrapper. |
src/frontend/astro.config.mjs |
Registers the wrapper plugin and externalizes scripts, sprite, and stylesheets. |
Review effort: Balanced
Summary
This PR is part of a series to cut the size of the frontend container image, which is currently about 4 GB. CI run 44388682589 produced 38,344 HTML pages totaling 9.4 GB. A typical docs page carries about 85 KB of inline SVG, 48 KB of inline script, and 13 KB of inline CSS, and every page repeats that markup. This PR moves it into shared, hashed
/_astro/assets that StaticHost already caches as immutable.src/scripts/*.inline.js, loaded with?url.<script is:inline src>. It has to setdata-apphost-langand the sidebar-collapsed attributes before first paint.defer, because it only needs the parsed DOM. Its one pre-paint step, hiding cookie controls when a previous visit found consent isn't required, is a ~200-byte inline snippet./_astro/cache.OsAwareTabs: both now use bundled Astro<script>s. EachOsAwareTabsrenders a hiddendata-os-aware-tabs-sync-keymarker that the shared modulesrc/scripts/os-aware-tabs.tsreads.build.inlineStylesheets: 'never'. Also setsvite.build.assetsInlineLimitso JavaScript and the icon sprite are never inlined. Astro had been inlining about 10–12 KB of small module scripts into every page.aria-hidden, and have a forced-colors fallback. Sidebar structure and data are unchanged.config/starlight-icon-sprite.mjsredirects every import of Starlight'sIcontosrc/components/starlight/Icon.astro. That wrapper serves 40 common icons from a 24 KB hashed sprite through<use>; any other icon still renders inline.bun run icon-spriteregenerates the sprite, and a unit test fails if it drifts from the installed Starlight icon set. Icons that fall back to inline markup keep the caller'sclass; a unit test covers this.Estimated savings, measured against live aspire.dev pages:
get-started/install-cli/, 266 KB): about 93 KB less (~35%).reference/api/csharp/aspire.hosting/, 1.53 MB): about 180 KB less (~12%). About 108 KB of that comes from the 390 sidebar carets.Expected merge conflicts with other PRs in the series:
src/frontend/patches/@astrojs__starlight@0.41.3.patchwill conflict with the locale-fallback PR.src/frontend/.starlight-icons/safelist.jsonwill conflict with the C# API sidebar PR. That file is regenerated, so regenerate it after merging.Behavior notes:
Astro.locals.tin the browser. That call always threw, so it never added the "(opens in new tab)" aria-label. I dropped the dead code; the external links'targetandrelbehavior is unchanged.Third-party links and affiliations
None
Validation
Everything below ran locally. I did not run
bun run buildlocally (it's left to CI), so this PR's CI build is the first full build with these changes.bunx vitest run --config vitest.config.ts(full unit suite) — passed (1,488 passed, 1 skipped) after the main changes. One assertion was then updated.bunx vitest run --config vitest.config.ts tests/unit/icon-sprite.vitest.test.ts tests/unit/custom-components.vitest.test.ts— passed (129/129) after that final change.bunx vitest run --config vitest.config.ts tests/unit/navigation-preferences.vitest.test.ts tests/unit/navigation-theme.vitest.test.ts tests/unit/page-weight-guardrails.vitest.test.ts tests/unit/custom-components.vitest.test.ts— passed (136/136).bunx eslint <changed files> --max-warnings 0andbunx prettier --checkon new and changed files — passed. Running ESLint over all ofsrc/scriptsalso reports errors in the untoucheddeployment-guard.tsandtooltips.ts.bunx playwright test tests/e2e/cookie-consent.spec.ts tests/e2e/ui-regressions.spec.ts tests/e2e/mobile-ux.spec.ts tests/e2e/site-ui-navigation.spec.ts --workers=2, run againstastro dev— 142 passed, 5 failed, 42 skipped. The failures were dev-server timeouts, connection resets, and 503s.--workers=1: 4 passed.ui-regressions.spec.ts:797("aligns the scroll-to-top control…") failed once more, then passed when run alone ondesktop-chromium. It looks flaky, but I didn't recheck it on the other viewports, so please watch it in CI.site-ui-navigation.spec.tswith--repeat-each=3on all projects — passed.aspire publishimage:api-search-contract.spec.ts:248was holding every script request until it had typed into the search box. The blocking head bootstrap stops HTML parsing, so the search box never appeared and the test deadlocked. The test now holds back only module scripts (the search controller), which is what it's meant to test.bunx playwright test tests/e2e/api-search-contract.spec.ts:248 --repeat-each=2— passed (6/6). It failed once on the cold first run of the dev server.bunx playwright test tests/e2e/live-status.spec.ts:703 tests/e2e/cookie-consent.spec.ts --workers=1— passed.bunx vitest run --config vitest.config.ts tests/unit/icon-sprite.vitest.test.ts tests/unit/navigation-preferences.vitest.test.ts tests/unit/navigation-theme.vitest.test.ts tests/unit/custom-components.vitest.test.ts— passed (135/135). The new icon-class assertion fails without the fix.OsAwareTabsdefault applies.